Triggers - Variables

Variables are a way of collecting numbers from inputs and using them in actions. Some examples would be:

Receiving a MIDI note on message and using the note value as a timeline number to start.
Using a DMX input channel to master the intensity of a group of fixtures.
Receiving a serial command on one Controller and outputting a related serial command on another.

Triggers that capture variables

Timeline Started, Timeline Ended and Timeline Released

The Timeline Started, Timeline Ended and Timeline Released triggers capture the timeline number as variable 1 if the Timeline parameter is set to Any.

Digital Input

The Digital Input trigger will capture the input number if the Input parameter of the trigger is set to Any.

If triggering from a RIO's digital input, the trigger will capture the input number if the Input parameter of the trigger is set to Any. The RIO number will be captured as variable 1 and the input number as variable 2 if both these parameters are set to Any. If only one of these parameters is set to Any then the captured number will be stored as variable 1.

Analog Input

Captures the analog input as a percentage in variable 1. For example, if the input range of the Controller’s analog input is set to 0-10V and the input is 4V then variable 1 will be 40%.

If triggering from a RIO's analog input, the analog input value is captured as a percentage in variable 1, then the RIO number (if set to Any) and the input number (if set to Any) in subsequent variables. If the RIO number and the input number are set to Any then variable 2 will be the RIO number and variable 3 will be the input number. If the RIO number is specified then variable 2 will be the input number.

Serial and Ethernet Input

Serial and Ethernet trigger data is entered as a string of data bytes, represented in either ASCII, hex or decimal form. Any single byte or group of consecutive bytes can be matched by specifying a wildcard, and the value stored as a variable. Multiple wildcards can be used and each will store into the next available variable. There are three types of wildcards supported:

<c> or <C>	Will match any single character (or byte) and store its raw value (0-255) as the next variable. You can add a length to the wildcard to match multiple characters and treat them as a single number - so <4c> would match a 32 bit number. Maximum length = 4.
<d> or <D>	Will match a decimal character (ASCII, 0-9) and store its numeric value (0-9) as the next variable. You can add a length to the wildcard to match multiple decimal characters and treat them as a single number - so <4d> would match four decimal characters and treat them as a number from 0-9999. Maximum length = 10.
<x> or <X>	Will match a hexadecimal character (ASCII, 0-f) and store its numeric value (0-15) as the next variable. You can add a length to the wildcard to match multiple hexadecimal characters and treat them as a single number - so <2x> would match two hexadecimal characters and treat them as a number from 0-255. Maximum length = 8.
<s> or <S>	Will capture a string of arbitrary length. To determine where the string ends, you must either: Specify a terminator yourself. For example, the trigger <s>\n would capture everything up to (but not including) the first \n character received. A terminator cannot be another variable, it must be a literal character, so <s><d> is not a valid trigger. Send a NULL character (0x00) to the Controller to indicate the end of the string. This NULL character is assumed and is not shown in the Designer interface. You can also say that you want to capture a string with a predetermined number of characters. For example, <4s> will capture 4 bytes and store it as a string. There is no need for a terminator in this case.

Note that if the input data does not match the wildcard type then the trigger does not match. So if you have specified the wildcard <3d> and the input is ASCII "12y" then the trigger will not match because the 3 characters were not all of the required decimal type.

When using Ethernet Inputs the last two variables in the trigger will be the IP address and the source port number of the device the message was received from.

If triggering from a RIO's serial input, the RIO number will be captured as the first variable if set to Any.

MIDI Input

In short MIDI messages, you can capture data 1 and/or data 2 into a variable by checking the 'Capture' checkbox. If both are checked, data 1 is variable 1 and data 2 is variable 2. For some short messages, i.e. Pitch Wheel, the two data bits are treated as a single 14 bit value. To capture this 14 bit value, check 'Capture' for data 1 and check the '14 bit variable' checkbox.

In MSC messages, if the 'Cue number' and 'List number' are left blank, the received values will be captured in variables. Cue number is captured into variable 1 and list number into variable 2.

Extended messages support the same wildcard format as serial triggers. The only difference is that <2c> captures a 16-bit value in serial triggers and it captures a 14-bit value in MIDI triggers.

If triggering from a RIO A's MIDI input, the RIO A number will be captured as the first variable if set to Any.

DMX Input

When a DMX Input trigger matches it will implicitly store the channel value as variable 1.

Audio Input

When an Audio input trigger matches it will implicitly store the level for the band as variable 1.

If triggering from a RIO A, the RIO A number will be captured if set to Any.

DALI Input

If the trigger is using a Min to Max range then the matching number will be stored as variable 1.

DALI Ballast Error

If All is selected instead of a specific address then the address of the ballast reporting the error will be stored as variable 1.

BPS Button

If the button number is set to Any, the trigger captures the pressed button as variable 1.

Alternatively, if the BPS station number is set to Any, then the station number is captured as variable 1 and the button number as variable 2.

Conditions that capture variables

Digital Word

This condition will capture a variable from the inputs set to match either value. This variable will be added on the end of any variables captured by the trigger.

Conditions that use variables

DALI Ballast Error

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Actions that use variables

Captured variables can then be used in actions by specifying the variable index (corresponding to the order in which the variables were captured). If you have multiple actions associated with a trigger then each action can use the variables independently.

Start, Release, Toggle, Resume and Pause Timeline

Rather than selecting a timeline as a property of the action you can specify the timeline number in a variable. This is a very powerful feature when you want an external system to be able to call up any one of a large number of timelines because you do not need to define separate triggers for each timeline.

Set, Increase and Decrease Intensity

The intensity level or increment can be passed in by a variable. Select the "Variable" option and then choose the variable index.

Set AVC Master

The video brightness and audio volume level can be passed in by a variable. Select the "Variable" option and then choose the variable index.

Set Fixture RGB

The Red, Green and Blue values for a group of fixtures can be passed in as variables. Select the "Variable" option for the colour you want to adjust and then choose the variable index. The fade time for the action can also be passed in as a variable. Select the "Variable" option and then choose the variable index.

Set DALI Level

The DALI group or ballast number on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

The level of a DALI ballast, group or all DALI ballasts can be passed in by a variable. Select the "Variable" option and then choose the variable index.

Recall DALI Scene

The DALI group or ballast number on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Recall a DALI scene on a specific interfaces single ballast, group or all of the ballasts. Select the "Variable" option and then choose the variable index.

DALI Command

The DALI group or ballast number on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Mark DALI Ballast Fixed

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

DALI Start Emergency Test

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

DALI Stop Emergency Test

The DALI ballast address on a specific interface can be passed in by variable. Select the relevant "Variable" option and then choose the variable index.

Set Timeline Rate

You can select the timeline to modify with a variable (as for Start Timeline). You can also choose to pass in the rate percentage using a variable.

Serial and Ethernet Output

In the same way that you can use wildcards to match data in a serial or Ethernet trigger, you can insert the value of captured variables into your serial output messages. The same wildcard types are supported to define how to output a variable:

<c>	Will output the value of a variable as a raw byte (0-255).
<d>	Will output the value of a variable as a decimal number (ASCII, 0-9).
<x>	Will output the value of a variable as a hexadecimal number (ASCII, 0-f). Any letters will be lowercase.
<X>	Will output the value of a variable as a hexadecimal number (ASCII, 0-f). Any letters will be uppercase.
<s>	Will output a captured string. <s> will output the entire captured string. <4s> would output the first 4 characters of the captured string.

As with input you can specify a length if you want to output the variable as a longer decimal or hexadecimal number. So a variable value of 175 output with <4d> would add ASCII "0175" to the serial output. Note that it is padded with leading zeros to fill the specified length. If the value was too large to express in the specified length it would be truncated from the left, so <2d> would output the number 123 as ASCII "23".

Output strings are allowed to begin with a wildcard. By default each wildcard takes the next variable in the order they were captured. If you want to output the variables in a different order then you can add a variable index to the wildcard in the form <3,2d> where 3 is the variable index. If you specify an output wildcard where there is no corresponding capture variable then it will have value of zero and output accordingly.

MIDI Output

Short messages can output a captured value for data 1 and data 2. Pick a variable using the 'Variable Index' controls. If data 1 is outputting a captured value, you can optionally send it as a 14-bit value, with the lower 7 bits in data 1 and the upper 7 bits in data 2, by checking '14 bit variable'.

Outputting a MSC message allows you to set the cue number and/or list number by choosing a variable with the 'Variable Index' controls.

Extended messages allow you to output captured variables using the same syntax as serial actions.

Run Script

Variables can be accessed from Lua scripts.

Set BPS Button LED

The button number and intensity level can be passed in by variables.

Notes

For hex strings, if a wildcard is inserted after an odd number of digits, the odd digit is treated as the lower 4 bits of the byte. For example, ff1<d> will be interpreted as ff01<d>.
If you want to match a '<' character, you must precede it with a backslash. In general, a backslash followed by any character will match that character (ignoring the backslash).